<HTML>
<!--
  -- Copyright (c) 1996-1999
  -- Silicon Graphics Computer Systems, Inc.
  --
  -- Permission to use, copy, modify, distribute and sell this software
  -- and its documentation for any purpose is hereby granted without fee,
  -- provided that the above copyright notice appears in all copies and
  -- that both that copyright notice and this permission notice appear
  -- in supporting documentation.  Silicon Graphics makes no
  -- representations about the suitability of this software for any
  -- purpose.  It is provided "as is" without express or implied warranty.
  --
  -- Copyright (c) 1994
  -- Hewlett-Packard Company
  --
  -- Permission to use, copy, modify, distribute and sell this software
  -- and its documentation for any purpose is hereby granted without fee,
  -- provided that the above copyright notice appears in all copies and
  -- that both that copyright notice and this permission notice appear
  -- in supporting documentation.  Hewlett-Packard Company makes no
  -- representations about the suitability of this software for any
  -- purpose.  It is provided "as is" without express or implied warranty.
  --
  -->
<Head>
<Title>Allocators</Title>
<!-- Generated by htmldoc -->
</HEAD>
<BODY BGCOLOR="#ffffff" LINK="#0000ee" TEXT="#000000" VLINK="#551a8b" 
	ALINK="#ff0000"> 
<IMG SRC="CorpID.gif" 
     ALT="SGI" HEIGHT="43" WIDTH="151"> 
<!--end header-->
<BR Clear>
<H1>Allocators</H1>

<Table CellPadding=0 CellSpacing=0 width=100%>
<TR>
<TD Align=left><Img src = "allocators.gif" Alt=""   WIDTH = "194"  HEIGHT = "38" ></TD>
<TD Align=right><Img src = "overview.gif" Alt=""   WIDTH = "194"  HEIGHT = "38" ></TD>
</TR>
<TR>
<TD Align=left VAlign=top><b>Category</b>: allocators</TD>
<TD Align=right VAlign=top><b>Component type</b>: overview</TD>
</TR>
</Table>

<h3>Summary</h3>
Allocators encapsulate allocation and deallocation of memory.  They
provide a low-level interface that permits efficient allocation of 
many small objects; different allocator types represent different
schemes for memory management.
<P>
Note that allocators simply allocate and deallocate memory, as opposed
to creating and destroying objects.  The STL also includes several
low-level algorithms for manipulating uninitialized memory.
<P>
Note also that allocators do not attempt to encapsulate multiple
memory models.  The C++ language only defines a single memory model
(the difference of two pointers, for example, is always <tt>ptrdiff_t</tt>),
and this memory model is the only one that allocators support. 
<i>This is a major change from the definition of allocators in the
original STL.</i> <A href="#1">[1]</A>
<h3>Description</h3>
The details of the allocator interface are still subject to change,
and we do not guarantee that specific member functions will remain in
future versions.  You should think of an allocator as a &quot;black box&quot;.
That is, you may select a container's memory allocation strategy by
instantiating the container template with a particular allocator <A href="#2">[2]</A>,
but you should not make any assumptions about how the container 
actually uses the allocator.  
<P>
The available allocators are as follows.  In most cases you shouldn't
have to worry about the distinction: the default allocator, <tt>alloc</tt>,
is usually the best choice.
<Table border>
<TR>
<TD VAlign=top>
<tt>alloc</tt>
</TD>
<TD VAlign=top>
The default allocator.  It is thread-safe, and usually has the best
   performance characteristics.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>pthread_alloc</tt>
</TD>
<TD VAlign=top>
A thread-safe allocator that uses a different memory pool for
   each thread;  you can only 
   use <tt>pthread_alloc</tt> if your operating system provides pthreads.
   <tt>Pthread_alloc</tt> is usually faster than <tt>alloc</tt>, especially on
   multiprocessor systems.  It can, however, cause
   resource fragmentation: memory deallocated in one
   thread is not available for use by other threads.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>single_client_alloc</tt>
</TD>
<TD VAlign=top>
A fast but thread-unsafe allocator.  In programs that only have
   one thread, this allocator might be faster than <tt>alloc</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>malloc_alloc</tt>
</TD>
<TD VAlign=top>
An allocator that simply uses the standard library function <tt>malloc</tt>.
   It is thread-safe but slow; the main reason why you might
   sometimes want to use it is to get more useful information from
   bounds-checking or leak-detection tools while you are debugging.
</TD>
</tr>
</table>
<h3>Examples</h3>
<pre>
vector&lt;double&gt; V(100, 5.0);     // Uses the default allocator.
vector&lt;double, single_client_alloc&gt; local(V.begin(), V.end());
</pre>
<h3>Concepts</h3>
<UL>
<LI>
Allocator
</UL>
<h3>Types</h3>
<UL>
<LI>
<tt>alloc</tt>
<LI>
<tt>pthread_alloc</tt>
<LI>
<tt>single_client_alloc</tt>
<LI>
<tt>malloc_alloc</tt>
<LI>
<tt><A href="raw_storage_iterator.html">raw_storage_iterator</A></tt>
</UL>
<h3>Functions</h3>
<UL>
<LI>
<tt><A href="construct.html">construct</A></tt>
<LI>
<tt><A href="destroy.html">destroy</A></tt>
<LI>
<tt><A href="uninitialized_copy.html">uninitialized_copy</A></tt>
<LI>
<tt><A href="uninitialized_fill.html">uninitialized_fill</A></tt>
<LI>
<tt><A href="uninitialized_fill_n.html">uninitialized_fill_n</A></tt>
<LI>
<tt><A href="get_temporary_buffer.html">get_temporary_buffer</A></tt>
<LI>
<tt><A href="return_temporary_buffer.html">return_temporary_buffer</A></tt>
</UL>
<h3>Notes</h3>
<P><A name="1">[1]</A>
The reason for this change is that the new interface reduces
memory fragmentation, and that it allows an implementation that
is both efficient and thread-safe.
<P><A name="2">[2]</A>
Different containers may use different allocators.  You might,
for example, have some containers that use the default allocator
<tt>alloc</tt> and others that use <tt>pthread_alloc</tt>.  Note, however, that
<tt>vector&lt;int&gt;</tt> and <tt>vector&lt;int, pthread_alloc&gt;</tt> are distinct types.
<h3>See also</h3>

<!--start footer--> 
<HR SIZE="6">
<A href="http://www.sgi.com/"><IMG SRC="surf.gif" HEIGHT="54" WIDTH="54" 
        ALT="[Silicon Surf]"></A>
<A HREF="index.html"><IMG SRC="stl_home.gif" 
        HEIGHT="54" WIDTH="54" ALT="[STL Home]"></A>
<BR>
<FONT SIZE="-2">
<A href="http://www.sgi.com/Misc/sgi_info.html" TARGET="_top">Copyright &copy; 
1999 Silicon Graphics, Inc.</A> All Rights Reserved.</FONT>
<FONT SIZE="-3"><a href="http://www.sgi.com/Misc/external.list.html" TARGET="_top">TrademarkInformation</A>
</FONT>
<P>
</BODY>
</HTML> 
